# Xiaozhi AI Architecture Audit

你现在负责对 Xiaozhi AI 项目进行一次 **Architecture Audit**。

本次任务是：

> **只分析，不修改代码。**

项目包含两个 Repository：

1. Xiaozhi Client —— 硬件端 / Device Runtime
2. Xiaozhi Server —— Server / AI / Backend

同时提供了一份《Xiaozhi AI 开放应用平台 Master Plan》。

Master Plan 是未来目标架构，但当前代码很可能与目标架构存在较大差异。

你的任务不是立即实现 Master Plan，而是：

> 找出当前系统是什么、已经具备什么、缺少什么，以及应该以什么最小代价逐步演进到目标架构。

---

## 一、禁止事项

本阶段禁止：

- 修改代码
- 删除代码
- 重构代码
- 创建新的业务模块
- 修改数据库
- 修改 API
- 修改协议
- 修改配置
- 修改硬件端逻辑

只允许：

- 阅读代码
- 分析代码
- 建立架构认知
- 输出分析报告
- 提出建议

---

# 二、Audit 范围

必须同时分析 Client 和 Server。

不要只看目录结构。

需要追踪真实代码调用链。

---

# 三、Client Audit

重点分析：

## 1. 当前 Runtime

回答：

- Client 当前启动流程是什么？
- 主循环在哪里？
- 当前 Conversation / Chat Runtime 在哪里？
- 用户说话 → ASR → LLM → TTS → 播放的完整调用链是什么？
- Audio Input / Output 如何实现？
- 是否已经存在 Event / Message / Command 机制？
- Server 与 Client 使用什么通信协议？

---

## 2. 硬件能力

整理当前已经存在的：

- 麦克风
- 扬声器
- 音频播放
- 音频录音
- VAD
- 按键
- LED
- 屏幕（如果有）
- SD Card
- 网络
- MQTT / WebSocket / HTTP 等通信能力

并指出哪些能力已经可以直接作为未来 Skill。

---

## 3. 找出当前可以抽象成 Skill 的能力

例如：

```text
play_audio
record_audio
listen
speak
wait
display
led
button
```

但不要强行创造不存在的能力。

必须基于真实代码分析。

---

## 4. 当前 Chat Architecture

重点回答：

```text
Audio Input
    ↓
VAD
    ↓
ASR
    ↓
Conversation
    ↓
LLM
    ↓
TTS
    ↓
Audio Output
```

实际代码中分别对应什么模块、类、函数和文件？

---

## 5. Task Runtime 插入点

重点分析：

未来增加：

```text
Task
 ↓
Step
 ↓
Skill
```

应该插入现有 Client 的什么位置？

重点回答：

> 如何做到“不破坏现有 Chat 功能”的情况下增加 Task Runtime。

---

# 四、Server Audit

重点分析：

## 1. Server 当前架构

分析：

- Server 启动入口
- API
- WebSocket
- MQTT
- Session
- User
- Device
- Conversation
- Audio
- ASR
- LLM
- TTS

之间的关系。

---

## 2. 当前对话链路

完整追踪：

```text
Device
 ↓
Server
 ↓
ASR
 ↓
Conversation
 ↓
LLM
 ↓
TTS
 ↓
Device
```

指出真实代码实现位置。

---

## 3. 数据库

列出当前与以下对象相关的数据表：

```text
User
Device
Conversation
Message
Audio
Session
```

以及其他与未来 Task 系统可能相关的表。

说明：

- 表结构
- 主键
- 外键
- 关系
- 当前数据生命周期

---

# 五、重点寻找未来 Domain Model 的落点

对以下概念逐一分析：

```text
App
Task
Step
Skill
InteractionMode
TaskInstance
StepInstance
Event
Audio
Assessment
Metric
Schedule
Plan
Subscription
```

对于每一个概念回答：

1. 当前代码中是否已经存在类似概念？
2. 如果存在，在哪里？
3. 是否可以复用？
4. 是否需要扩展？
5. 是否需要新建？
6. 最适合放在哪个 Repository / Module？

---

# 六、重点分析 InteractionMode

Master Plan 中：

> InteractionMode 不是业务场景，而是 Xiaozhi 的硬件交互方式。

重点确认当前代码是否存在类似：

```text
Chat
Audio Playback
Recording
Listening
Translation
Game
```

或者其他模式。

分析：

> InteractionMode 最适合放在 Client、Server，还是两边都有？

并给出推荐。

---

# 七、重点分析 Task Runtime

这是本次 Audit 最重要的部分。

回答：

当前系统应该如何从：

```text
Conversation Runtime
```

逐步演进为：

```text
Device Runtime
    ├── Chat Runtime
    └── Task Runtime
          ├── Step
          └── Skill
```

不要直接设计新代码。

先分析：

> 当前代码在哪里最适合插入这个 Runtime。

---

# 八、重点分析 Audio / Recording

未来 Server 需要保存儿童 Task 执行过程中的语音。

因此分析：

- 当前录音在哪里产生？
- 音频是否已经上传 Server？
- 音频格式是什么？
- 是否可以保存原始音频？
- 当前音频生命周期是什么？
- 是否存在 Audio ID？
- 是否存在 Session ID？
- 是否可以关联到 TaskInstance / StepInstance？

指出未来最小改造方案。

---

# 九、重点分析 Event

检查当前是否已经存在：

```text
Event
Message
Command
State
Callback
```

等机制。

如果存在：

> 判断能否演进成统一 Event Architecture。

如果不存在：

> 指出最合适的插入位置。

---

# 十、最终输出 Audit Report

最终不要只输出总结。

必须输出以下内容：

## 1. Current Architecture

分别画出：

```text
Client Architecture
Server Architecture
```

最好使用 Mermaid。

---

## 2. Current Runtime Call Graph

画出：

```text
用户说话
 ↓
...
```

对应真实代码模块。

---

## 3. Existing Capability Map

整理：

```text
Capability
Current Implementation
Repository
Module
Reusable?
Required Change
```

---

## 4. Domain Mapping

建立：

```text
Master Plan Domain
        ↓
Current Code
        ↓
Gap
        ↓
Recommended Location
```

---

## 5. Architecture Gap

明确列出：

```text
P0 必须解决
P1 后续解决
P2 未来平台化解决
```

---

## 6. Recommended Evolution Architecture

不是要求立即实现。

而是说明：

```text
Current
   ↓
Phase 1
   ↓
Phase 2
   ↓
Phase 3
   ↓
Target Architecture
```

---

## 7. 最关键的修改点

最终明确列出：

### Client

需要改哪些模块。

### Server

需要改哪些模块。

### Database

需要新增/修改哪些实体。

### Protocol

需要增加哪些消息。

### API

需要增加哪些接口。

但此阶段只提出，不实现。

---

# 十一、最终必须回答的核心问题

请特别回答以下问题：

### Q1

当前 Chat Runtime 能否直接作为未来 Task Runtime 的一个子 Runtime？

---

### Q2

Task Runtime 最适合放在 Client 还是 Server？

请结合当前代码分析，而不是只根据理论回答。

---

### Q3

Step 状态应该由 Client 保存、Server 保存，还是两边都有？

---

### Q4

Task 执行过程中 Server 与 Client 的状态同步机制应该如何设计？

---

### Q5

App / Task / Resource 是否可以完全通过 JSON + Audio Resource 下发，而不需要 OTA？

如果不能，请指出哪些能力必须固化到 Firmware。

---

### Q6

当前代码距离：

```text
App
 ↓
Task
 ↓
Step
 ↓
Skill
 ↓
Device Capability
```

最大的架构障碍是什么？

---

### Q7

如何以最小修改实现第一个：

```text
英语复读 Task
```

而不破坏现有 Chat？

---

### Q8

如何以最小修改实现：

```text
英语跟读
 ↓
录音
 ↓
上传
 ↓
ASR
 ↓
Assessment
```

---

# 十二、最终结论

最后给出：

```text
Architecture Audit Conclusion
```

并明确：

1. 当前架构可以保留什么
2. 当前架构必须改什么
3. 第一阶段应该改什么
4. 哪些事情现在绝对不要做
5. 下一阶段应该如何生成 Phase 1 Coding Plan

再次强调：

> 本次任务的目标不是写代码，而是建立对当前系统的完整架构认知，并找到从 Current Architecture 到 Master Plan 的最小演进路径。

完成 Audit 后停止。

等待下一步指令。